<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Reporting Stories</title>
</head>

<body>

<h2>Story Reporters</h2>

<p>Reporting is an essential element of BDD as it allows to monitor
the outcome of the stories that have been run. At the heart of JBehave's
reporting is the <a
	href="javadoc/core/org/jbehave/core/reporters/StoryReporter.html">StoryReporter</a>,
to which events are reported as they occur.</p>

<p>Currently, the story reporters supported are:</p>
<ul>
	<li><a
		href="javadoc/core/org/jbehave/core/reporters/ConsoleOutput.html">ConsoleOutput</a>:
	a text-based console output</li>
	<li><a
		href="javadoc/core/org/jbehave/core/reporters/IdeOnlyConsoleOutput.html">IdeOnlyConsoleOutput</a>:
	a text-based console output, which only reports events when running in
	IDEs (Eclipse and IDEA supported).</li>
	<li><a
		href="javadoc/core/org/jbehave/core/reporters/TxtOutput.html">TxtOutput</a>:
	a text-based file output</li>
	<li><a
		href="javadoc/core/org/jbehave/core/reporters/HtmlOutput.html">HtmlOutput</a>:
	an HTML file output</li>
    <li><a
        href="javadoc/core/org/jbehave/core/reporters/HtmlTemplateOutput.html">HtmlTemplateOutput</a>:
    an HTML template-based file output.  By default, a Freemarker-based template processor is used but a different 
    implementation based on a different templating system can be provided.</li>
	<li><a
		href="javadoc/core/org/jbehave/core/reporters/XmlOutput.html">XmlOutput</a>:
	an XML file output</li>
	<li><a
		href="javadoc/core/org/jbehave/core/reporters/PostStoryStatisticsCollector.html">PostStoryStatisticsCollector</a>:
	collects statistics and stores them as properties after story is run</li>
	<li><a
		href="javadoc/core/org/jbehave/core/reporters/DelegatingStoryReporter.html">DelegatingStoryReporter</a>:
	used by the StoryReporterBuilder to delegate to any number of reporters
	as a proxy.</li>
</ul>

<p>The <a
	href="javadoc/core/org/jbehave/core/reporters/StoryReporterBuilder.html">StoryReporterBuilder</a>
allows to configure multiple story reporters with pre-configured
formats: CONSOLE, TXT, HTML, HTML_TEMPLATE and XML.</p>
<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public abstract class TraderStory extends JUnitStory {

    private final CrossReference xref = new CrossReference();

    public TraderStory() {
        configuredEmbedder().embedderControls().doGenerateViewAfterStories(true).doIgnoreFailureInStories(true)
                .doIgnoreFailureInView(true).useThreads(2).useStoryTimeoutInSecs(60);
        // Uncomment to set meta filter, which can also be set via Ant or Maven
        // configuredEmbedder().useMetaFilters(Arrays.asList("+theme parametrisation"));
    }

    @Override
    public Configuration configuration() {
        Class<? extends Embeddable> embeddableClass = this.getClass();
        Properties viewResources = new Properties();
        viewResources.put("decorateNonHtml", "true");
        // Start from default ParameterConverters instance
        ParameterConverters parameterConverters = new ParameterConverters();
        // factory to allow parameter conversion and loading from external
        // resources (used by StoryParser too)
        ExamplesTableFactory examplesTableFactory = new ExamplesTableFactory(new LocalizedKeywords(),
                new LoadFromClasspath(embeddableClass), parameterConverters);
        // add custom converters
        parameterConverters.addConverters(new DateConverter(new SimpleDateFormat("yyyy-MM-dd")),
                new ExamplesTableConverter(examplesTableFactory));

        return new MostUsefulConfiguration()
                .useStoryControls(new StoryControls().doDryRun(false).doSkipScenariosAfterFailure(false))
                .useStoryLoader(new LoadFromClasspath(embeddableClass))
                .useStoryParser(new RegexStoryParser(examplesTableFactory))
                .useStoryPathResolver(new UnderscoredCamelCaseResolver())
                .useStoryReporterBuilder(
                        new StoryReporterBuilder()
                                .withCodeLocation(CodeLocations.codeLocationFromClass(embeddableClass))
                                .withDefaultFormats().withPathResolver(new ResolveToPackagedName())
                                .withViewResources(viewResources).withFormats(CONSOLE, TXT, HTML, XML)
                                .withFailureTrace(true).withFailureTraceCompression(true).withCrossReference(xref))
                .useParameterConverters(parameterConverters)
                // use '%' instead of '$' to identify parameters
                .useStepPatternParser(new RegexPrefixCapturingPatternParser("%")) 
                .useStepMonitor(xref.getStepMonitor());
    }

    @Override
    public InjectableStepsFactory stepsFactory() {
        return new InstanceStepsFactory(configuration(), new TraderSteps(new TradingService()), new AndSteps(), new MetaParametrisationSteps(),
                new CalendarSteps(), new PriorityMatchingSteps(), new PendingSteps(), new ParametrisedSteps(), new SandpitSteps(),
                new SearchSteps(), new BeforeAfterSteps(), new CompositeSteps(), new CompositeNestedSteps(), new NamedParametersSteps());
    }
}
]]>
</script>

<p>Note that we use the <a
	href="javadoc/core/org/jbehave/core/reporters/StoryReporterBuilder.html">StoryReporterBuilder</a>
to implement a builder pattern for file-based reporters via the <a
	href="javadoc/core/org/jbehave/core/reporters/FilePrintStreamFactory.html">FilePrintStreamFactory</a>.
The file path resolution strategy from a story path to a report file
path is definable via the <a
	href="javadoc/core/org/jbehave/core/reporters/FilePrintStreamFactory.FilePathResolver.html">FilePathResolver</a>.
By default, it uses the <a
	href="javadoc/core/org/jbehave/core/reporters/FilePrintStreamFactory.ResolveToPackagedName.html">ResolveToPackagedName</a>
whereby the story path is resolved to a Java package. So, e.g., if the
story path is <b>com/example/my_cool.story</b>, we'll end up with file
report outputs of the form: <b>com.example.my_cool.[format]</b> (where <b>format</b>
is any of <b>txt,html,xml</b> in the example above). An alternative
strategy, is the <a
	href="javadoc/core/org/jbehave/core/reporters/FilePrintStreamFactory.ResolveToSimpleName.html">ResolveToSimpleName</a>,
whereby only the simple name portion, without the package structure, is
considered, i.e. we'd end up with file report outputs of the form: <b>my_cool.[format]</b></p>

<p>The builder provides defaults for all the formats supported, but
if the user needs to create a bespoke instance of a reporter for a given
format, it can be easily done by overriding the default. E.g. to
override the reporter for <b>TXT</b> format to use a ".text" extension:</p>
<pre class="brush: java">
        StoryReporterBuilder builder = new StoryReporterBuilder() {
            public StoryReporter reporterFor(String storyPath, Format format) {
                switch (format) {
                case TXT:
                    factory.useConfiguration(new FileConfiguration("text"));
                    return new TxtOutput(factory.createPrintStream(), new Properties(), 
                                                        new LocalizedKeywords(), true);                    
                default:
                    return super.reporterFor(storyPath, format);
                }
            }
        };
</pre>

<h2>Code Locations</h2>

<p>The file-based print stream factory for the story reporting
requires a <a href="javadoc/core/org/jbehave/core/io/StoryLocation.html">StoryLocation</a>
to be provided in order to derive from it the output file paths (with
the appropriate format extension). The story location, in turn, requires
a code location URL and a story path.</p>

<p>The code location URLs can be created from different sources, via
static methods in the <a
	href="javadoc/core/org/jbehave/core/io/CodeLocations.html">CodeLocations</a>
utility class:</p>

<ul>
	<li><a
		href="javadoc/core/org/jbehave/core/io/CodeLocations.html#codeLocationFromClass(java.lang.Class)">codeLocationFromClass(java.lang.Class)</a>:
	returns the code location of the class resource</li>
	<li><a
		href="javadoc/core/org/jbehave/core/io/CodeLocations.html#codeLocationFromPath(java.lang.String)">codeLocationFromFromPath(java.lang.String)</a>:
	returns the code location of a local file path</li>
	<li><a
		href="javadoc/core/org/jbehave/core/io/CodeLocations.html#codeLocationFromURL(java.lang.String)">codeLocationFromFromURL(java.lang.String)</a>:
	returns the code location of a generic url (from its String external
	form representation)</li>
</ul>

<h2>View Generation</h2>

<p>The generation of the reports is only the first part of a
complete HTML-based reporting solution. Next we generate the stories
view, aggregating all the reports that have been configured and written
to a given output directory, and presenting a collective index view for
all formats configured. Moreover, we can style the reports, both for
HTML and non-HTML report formats, by decorating their content with CSS
and syntax highlighting. The decorating of non-HTML reports can be
switched off if one prefers the raw content accessible via a URL:</p>

<pre class="brush: java">
    Properties viewResources = new Properties();
	viewResources("decorateNonHtml","false");
    new StoryReporterBuilder().useViewResources(viewResources);        
</pre>

<p>The view generation is the responsibility of the <a
	href="javadoc/core/org/jbehave/core/reporters/ViewGenerator.html">ViewGenerator</a>.
JBehave provides an implementation (<a
	href="javadoc/core/org/jbehave/core/reporters/FreemarkerViewGenerator.html">FreemarkerViewGenerator.</a>)
based on <a href="http://freemarker.org">Freemarker</a> to allow a
templateable and easily styleable way to generate the view.  JBehave also provides a more generic <a
    href="javadoc/core/org/jbehave/core/reporters/TemplateableViewGenerator.html">TemplateableViewGenerator</a>  
    which supports any <a
    href="javadoc/core/org/jbehave/core/reporters/TemplateProcessor.html">TemplateProcessorr</a> to generate
    the view.</p>

<p>The default resources required for the view generation are
bundled in the <b>jbehave-core-resources.zip</b> but can be overridden.
The Freemarker templates (the ftl/** files) need to be the classpath for
the <b>FreemarkerViewGenerator</b> to find them, while the look and feel
resources (the js/* and style/* files) need to be copied to the <b>target/jbehave/view</b>
directory (or wherever the story reporter builder relative directory is
configured to be). Also note that the default style makes use of images
found in the <b>jbehave-site-resources.zip</b>.</p>

<span class="followup">Maven users can use the <b>unpack-view-resources</b>
goal which will derive the view directory from the configured Embedder
and unpack to it the resources specified as normal project dependencies
(provided they match the type and artifactId filters, see <a
	href="maven-goals.html">maven goals</a> for more details).</span>

<h2>Reporting Statistics</h2>

<p>The <b>PostStoryStatisticsCollector</b> is treated in the view
generation slightly differently from other reports, in that the
statistics are displayed on the index view page, if available. To ensure
they are always available the story reporter builder is configured to
have <b>stats</b> as a default format (although the default formats need
to be added to the builder).</p>

<h2>Default Formats</h2>

<p>Default formats allow users to define a builder that can be used
in multiple configurations without having to repeat tediously all the
formats required, if these are used consistently. By default, "stats" is
the only default format (used for collecting reporting statistics). To
modify simply override the method <b>withDefaultFormats()</b>. E.g. to
add "txt" as a default format:</p>
<pre class="brush: java">
    new StoryReporterBuilder(){
        public StoryReporterBuilder withDefaultFormats() {
            return withFormats(STATS, TXT);
        }
    }
</pre>

<p>By default, JBehave writes file-based reports to the relative
directory <b>jbehave</b> (relative to the story class code source
location, e.g. the <b>target</b> directory in Maven), but this can be
changed via the builder:</p>

<pre class="brush: java">
    new StoryReporterBuilder().withRelativeDirectory("my-output")
</pre>

<h2>Next?</h2>

<span class="followup">The trader examples are configured to have
a fully-working end-to-end use of JBehave reporting (be sure to read the
instructions on <a href="running-examples.html">running examples</a>).
After running the build simply open the page <b>target/jbehave/view/reports.html</b>
of the appropriate trader example modules.</span>

<div class="clear">
<hr />
</div>

</body>
</html>